home *** CD-ROM | disk | FTP | other *** search
/ Amiga Magazin: Amiga-CD 1996 March / Amiga-CD 1996 #3.iso / amiga_technologies / include_i / dos / rdargs.i < prev    next >
Text File  |  1996-01-19  |  4KB  |  116 lines
  1.     IFND    DOS_RDARGS_I
  2. DOS_RDARGS_I SET 1
  3. **
  4. **    $VER: rdargs.i 36.7 (12.7.90)
  5. **    Includes Release 40.16
  6. **
  7. **    ReadArgs() structure definitions
  8. **
  9. **    (C) Copyright 1989-1995 ESCOM AG
  10. **        All Rights Reserved
  11. **
  12.  
  13.     IFND EXEC_NODES_I
  14.     INCLUDE "exec/nodes.i"
  15.     ENDC
  16.  
  17. **********************************************************************
  18. *
  19. * The CSource data structure defines the input source for "RdItem()"
  20. * as well as the ReadArgs call.  It is a publicly defined structure
  21. * which may be used by applications which use code that follows the
  22. * conventions defined for access.
  23. *
  24. * When passed to the dos.library functions, the value passed as
  25. * struct *CSource is defined as follows:
  26. *    if ( CSource == 0)    Use buffered IO "ReadChar()" as data source
  27. *    else            Use CSource for input character stream
  28. *
  29. * The following two pseudo-code routines define how the CSource structure
  30. * is used:
  31. *
  32. * long CS_ReadChar( struct CSource *CSource )
  33. * {
  34. *    if ( CSource == 0 )    return ReadChar();
  35. *    if ( CSource->CurChr >= CSource->Length )    return ENDSTREAMCHAR;
  36. *    return CSource->Buffer[ CSource->CurChr++ ];
  37. * }
  38. *
  39. * BOOL CS_UnReadChar( struct CSource *CSource )
  40. * {
  41. *    if ( CSource == 0 )    return UnReadChar();
  42. *    if ( CSource->CurChr <= 0 )    return FALSE;
  43. *    CSource->CurChr--;
  44. *    return TRUE;
  45. * }
  46. *
  47. * To initialize a struct CSource, you set CSource->CS_Buffer to
  48. * a string which is used as the data source, and set CS_Length to
  49. * the number of characters in the string.  Normally CS_CurChr should
  50. * be initialized to ZERO, or left as it was from prior use as
  51. * a CSource.
  52. *
  53. **********************************************************************
  54.  
  55.     STRUCTURE    CSource,0
  56.         APTR    CS_Buffer
  57.         LONG    CS_Length
  58.         LONG    CS_CurChr
  59.         LABEL    CS_SIZEOF
  60.  
  61. **********************************************************************
  62. *
  63. * The RDArgs data structure is the input parameter passed to the DOS
  64. * ReadArgs() function call.
  65. *
  66. * The RDA_Source structure is a CSource as defined above;
  67. * if RDA_Source.CS_Buffer is non-null, RDA_Source is used as the input
  68. * character stream to parse, else the input comes from the buffered STDIN
  69. * calls ReadChar/UnReadChar.
  70. *
  71. * RDA_DAList is a private address which is used internally to track
  72. * allocations which are freed by FreeArgs().  This MUST be initialized
  73. * to NULL prior to the first call to ReadArgs().
  74. *
  75. * The RDA_Buffer and RDA_BufSiz fields allow the application to supply
  76. * a fixed-size buffer in which to store the parsed data.  This allows
  77. * the application to pre-allocate a buffer rather than requiring buffer
  78. * space to be allocated.  If either RDA_Buffer or RDA_BufSiz is NULL,
  79. * the application has not supplied a buffer.
  80. *
  81. * RDA_ExtHelp is a text string which will be displayed instead of the
  82. * template string, if the user is prompted for input.
  83. *
  84. * RDA_Flags bits control how ReadArgs() works.    The flag bits are
  85. * defined below.  Defaults are initialized to ZERO.
  86. *
  87. **********************************************************************
  88.  
  89.     STRUCTURE    RDArgs,0
  90.         STRUCT    RDA_Source,CS_SIZEOF    ; Select input source
  91.         APTR    RDA_DAList        ; PRIVATE.
  92.         LONG    RDA_Buffer        ; Optional string parsing space.
  93.         LONG    RDA_BufSiz        ; Size of RDA_Buffer (0..n)
  94.         APTR    RDA_ExtHelp        ; Optional extended help
  95.         LONG    RDA_Flags        ; Flags for any required control
  96.         LABEL    RDA_SIZEOF
  97.  
  98.     BITDEF    RDA,STDIN,0    ; Use "STDIN" rather than "COMMAND LINE"
  99.     BITDEF    RDA,NOALLOC,1    ; If set, do not allocate extra string space.
  100.     BITDEF    RDA,NOPROMPT,2    ; Disable reprompting for string input.
  101.  
  102. **********************************************************************
  103. * Maximum number of template keywords which can be in a template passed
  104. * to ReadArgs(). IMPLEMENTOR NOTE - must be a multiple of 4.
  105. **********************************************************************
  106. MAX_TEMPLATE_ITEMS    equ    100
  107.  
  108. **********************************************************************
  109. * Maximum number of MULTIARG items returned by ReadArgs(), before
  110. * an ERROR_LINE_TOO_LONG.  These two limitations are due to stack
  111. * usage.  Applications should allow "a lot" of stack to use ReadArgs().
  112. **********************************************************************
  113. MAX_MULTIARGS    equ    128
  114.  
  115.     ENDC    ; DOS_RDARGS_I
  116.